bunqueue 2.8.60 → 2.9.2

package/dist/infrastructure/cloud/statsRefresh.js

@@ -7,6 +7,7 @@ import { hostname, arch, platform, cpus } from 'os';
 import { throughputTracker } from '../../application/throughputTracker';
 import { latencyTracker } from '../../application/latencyTracker';
 import { VERSION } from '../../shared/version';
+import { clientStorageStatus } from '../../shared/storageHealth';
 /** Cached hostname — computed once */
 const HOST = hostname();
 /** Cached runtime info — computed once */
@@ -22,7 +23,7 @@ export function buildStatsRefresh(qm) {
     const rates = throughputTracker.getRates();
     const percentiles = latencyTracker.getPercentiles();
     const averages = latencyTracker.getAverages();
-    const storage = qm.getStorageStatus();
+    const storage = clientStorageStatus(qm.getStorageStatus());
     const mem = process.memoryUsage();
     const workerStats = qm.workerManager.getStats();
     const queueNames = qm.listQueues();

package/dist/infrastructure/cloud/types/command.d.ts

@@ -1,4 +1,4 @@
-import type { QueueManager } from '../../../application/queueManager';
+import type { CloudQueueAdapter } from '../queueAdapter/types';
 import type { CloudSnapshot } from './snapshot';
 /** Incoming command from the dashboard. */
 export interface CloudCommand {
@@ -41,4 +41,4 @@ export interface CommandContext {
     getSnapshot?: () => Promise<CloudSnapshot>;
     triggerBackup?: () => Promise<unknown>;
 }
-export type CloudCommandHandler = (queueManager: QueueManager, command: CloudCommand, context?: CommandContext) => unknown;
+export type CloudCommandHandler = (adapter: CloudQueueAdapter, command: CloudCommand, context?: CommandContext) => unknown;

package/dist/infrastructure/persistence/jobOptionsBlob.d.ts

@@ -11,6 +11,7 @@ export interface StoredJobOptions {
     debounceId: string | null;
     debounceTtl: number | null;
     durable: boolean;
+    groupFifoOrder: string | null;
 }
 /** Persist generation policies that do not have dedicated legacy columns. */
 export declare function encodeJobOptions(job: Job): Uint8Array;

package/dist/infrastructure/persistence/jobOptionsBlob.js

@@ -1,3 +1,4 @@
+import { getGroupFifoOrder } from '../../domain/job/groupFifoOrder';
 import { storageLog } from '../../shared/logger';
 import { decodeMessagePack, encodeMessagePack } from '../../shared/msgpack';
 const DEFAULTS = {
@@ -12,10 +13,14 @@ const DEFAULTS = {
     debounceId: null,
     debounceTtl: null,
     durable: false,
+    groupFifoOrder: null,
 };
+function validStoredOrder(value) {
+    return typeof value === 'string' && /^[1-9]\d*$/.test(value) ? value : null;
+}
 /** Persist generation policies that do not have dedicated legacy columns. */
 export function encodeJobOptions(job) {
-    return encodeMessagePack({
+    const options = {
         backoffConfig: job.backoffConfig,
         repeat: job.repeat,
         stackTraceLimit: job.stackTraceLimit,
@@ -27,7 +32,9 @@ export function encodeJobOptions(job) {
         debounceId: job.debounceId,
         debounceTtl: job.debounceTtl,
         durable: job.durable ?? false,
-    });
+    };
+    const order = getGroupFifoOrder(job);
+    return encodeMessagePack(order === null ? options : { ...options, groupFifoOrder: String(order) });
 }
 /** Decode current blobs while giving pre-v34 rows their historical defaults. */
 export function decodeJobOptions(blob, context) {
@@ -47,6 +54,7 @@ export function decodeJobOptions(blob, context) {
             debounceId: decoded.debounceId ?? null,
             debounceTtl: decoded.debounceTtl ?? null,
             durable: decoded.durable ?? false,
+            groupFifoOrder: validStoredOrder(decoded.groupFifoOrder),
         };
     }
     catch (error) {

package/dist/infrastructure/persistence/migrations.js

@@ -117,4 +117,15 @@ CREATE INDEX IF NOT EXISTS idx_queue_metric_buckets_window
 `,
     // Persist repeat-chain and advanced per-generation job policies.
     34: 'ALTER TABLE jobs ADD COLUMN extended_options BLOB;',
+    // Persist per-group rate and concurrency overrides.
+    35: `
+CREATE TABLE IF NOT EXISTS group_state (
+    queue TEXT NOT NULL,
+    group_id TEXT NOT NULL,
+    rate_limit INTEGER,
+    rate_duration INTEGER,
+    concurrency_limit INTEGER,
+    PRIMARY KEY (queue, group_id)
+);
+`,
 };

package/dist/infrastructure/persistence/postgres/admission.d.ts

@@ -0,0 +1,18 @@
+import type { TransactionSQL } from 'bun';
+import { type Job, type JobId } from '../../../domain/types/job';
+import { type PostgresContext } from './context';
+import type { PostgresAdmissionResult } from './admissionResult';
+export interface AdmitPostgresJobOptions {
+    readonly rejectExisting?: boolean;
+    readonly linkParent?: boolean;
+    readonly dependencyLocksHeld?: boolean;
+    readonly queueLifecycleLocksHeld?: boolean;
+    readonly dependencyExistenceCheckDeferred?: boolean;
+    readonly completionConsumerExemptions?: readonly JobId[];
+    /** Flow caller already holds identity locks and batches completion, queue, and event writes. */
+    readonly preparedFlow?: {
+        readonly now: number;
+    };
+}
+/** Insert one job inside the caller's transaction and return its authoritative generation. */
+export declare function admitPostgresJob(tx: TransactionSQL, ctx: PostgresContext, job: Job, options?: AdmitPostgresJobOptions): Promise<PostgresAdmissionResult>;

package/dist/infrastructure/persistence/postgres/admission.js

@@ -0,0 +1,196 @@
+import { MAX_TIMELINE_ENTRIES } from '../../../domain/types/job';
+import { decodePostgresJob, encodePostgresValue, postgresStateForJob } from './codec';
+import { databaseNow, recordPostgresEvent } from './context';
+import { clearPostgresDeduplication, extendPostgresDeduplication, recordPostgresDeduplicationRemoval, } from './deduplication';
+import { updatePostgresJobParentInTransaction } from './relationships';
+import { assertPostgresDependenciesExist, lockPostgresDependencyCompletions, postgresDependenciesSatisfied, tryLockPostgresDependencyCompletions, } from './dependencyPromotion';
+import { assertNoLivePostgresCompletionConsumers, retirePostgresCompletionGenerations, } from './completionLifecycle';
+import { lockPostgresAdmissionKeys } from './batchAdmission';
+import { linkedPostgresParentQueue, lockPostgresAdmissionParent } from './admissionParent';
+import { lockPostgresAdmissionQueues, registerPostgresAdmissionQueues } from './queueLifecycle';
+function isLive(state) {
+    return ['waiting', 'prioritized', 'delayed', 'waiting-children', 'active'].includes(state);
+}
+async function findById(tx, ctx, id) {
+    const rows = await tx `
+    SELECT * FROM bunqueue_jobs
+    WHERE namespace = ${ctx.config.namespace} AND id = ${id}
+    FOR UPDATE
+  `;
+    return rows[0] ? decodePostgresJob(rows[0]) : null;
+}
+async function findByUniqueKey(tx, ctx, job) {
+    if (!job.uniqueKey)
+        return null;
+    const rows = await tx `
+    SELECT * FROM bunqueue_jobs
+    WHERE namespace = ${ctx.config.namespace}
+      AND queue = ${job.queue}
+      AND unique_key = ${job.uniqueKey}
+      AND state IN ('waiting', 'prioritized', 'delayed', 'waiting-children', 'active')
+    ORDER BY created_at, id
+    LIMIT 1
+    FOR UPDATE
+  `;
+    return rows[0] ?? null;
+}
+async function deleteTerminalGeneration(tx, ctx, id) {
+    await tx `
+    DELETE FROM bunqueue_job_logs
+    WHERE namespace = ${ctx.config.namespace} AND job_id = ${id}
+  `;
+    await tx `
+    DELETE FROM bunqueue_repeat_links
+    WHERE namespace = ${ctx.config.namespace}
+      AND (original_id = ${id} OR successor_id = ${id})
+  `;
+    await tx `
+    DELETE FROM bunqueue_flow_failures
+    WHERE namespace = ${ctx.config.namespace} AND parent_id = ${id}
+  `;
+    await tx `
+    DELETE FROM bunqueue_dependencies
+    WHERE namespace = ${ctx.config.namespace} AND job_id = ${id}
+  `;
+    await tx `
+    DELETE FROM bunqueue_completions
+    WHERE namespace = ${ctx.config.namespace} AND job_id = ${id}
+  `;
+    await tx `
+    DELETE FROM bunqueue_jobs
+    WHERE namespace = ${ctx.config.namespace} AND id = ${id}
+  `;
+}
+async function insertDependencies(tx, ctx, job) {
+    for (const dependencyId of new Set(job.dependsOn.map(String))) {
+        await tx `
+      INSERT INTO bunqueue_dependencies (namespace, job_id, dependency_id)
+      VALUES (${ctx.config.namespace}, ${String(job.id)}, ${dependencyId})
+      ON CONFLICT DO NOTHING
+    `;
+    }
+}
+async function insertRow(tx, ctx, job, state, now) {
+    await tx `
+    INSERT INTO bunqueue_jobs (
+      namespace, id, queue, payload, state, priority, lifo, run_at, created_at,
+      started_at, completed_at, attempts, max_attempts, ttl, timeout, unique_key,
+      unique_expires_at, custom_id, group_id, group_order, parent_id
+    ) VALUES (
+      ${ctx.config.namespace}, ${String(job.id)}, ${job.queue}, ${encodePostgresValue(job)},
+      ${state}, ${job.priority}, ${job.lifo}, ${job.runAt}, ${job.createdAt},
+      ${job.startedAt}, ${job.completedAt}, ${job.attempts}, ${job.maxAttempts}, ${job.ttl},
+      ${job.timeout}, ${job.uniqueKey},
+      ${job.uniqueKey && job.deduplicationTtl !== null ? now + job.deduplicationTtl : null},
+      ${job.customId}, ${job.groupId},
+      CASE WHEN CAST(${job.groupId} AS TEXT) IS NULL
+        THEN NULL ELSE nextval('bunqueue_group_order_seq') END,
+      ${job.parentId}
+    )
+  `;
+    await insertDependencies(tx, ctx, job);
+}
+/** Insert one job inside the caller's transaction and return its authoritative generation. */
+export async function admitPostgresJob(tx, ctx, job, options = {}) {
+    const parentQueue = options.linkParent === false ? null : linkedPostgresParentQueue(job);
+    if (!options.queueLifecycleLocksHeld) {
+        await lockPostgresAdmissionQueues(tx, ctx, [job.queue]);
+    }
+    if (!options.dependencyLocksHeld) {
+        await lockPostgresDependencyCompletions(tx, ctx, [job.id, ...job.dependsOn]);
+    }
+    if (parentQueue)
+        await lockPostgresAdmissionParent(tx, ctx, job, parentQueue);
+    if (!options.preparedFlow)
+        await lockPostgresAdmissionKeys(tx, ctx, [job]);
+    const now = options.preparedFlow?.now ?? (await databaseNow(tx));
+    const existingById = await findById(tx, ctx, String(job.id));
+    if (existingById) {
+        if (options.rejectExisting)
+            throw new Error(`Flow job ${String(job.id)} already exists`);
+        if (isLive(existingById.state)) {
+            return { job: existingById.job, inserted: false, state: existingById.state };
+        }
+    }
+    let existingByKeyRow = await findByUniqueKey(tx, ctx, job);
+    if (existingByKeyRow &&
+        existingByKeyRow.unique_expires_at !== null &&
+        Number(existingByKeyRow.unique_expires_at) <= now) {
+        await clearPostgresDeduplication(tx, ctx, existingByKeyRow, now);
+        existingByKeyRow = null;
+    }
+    if (existingByKeyRow) {
+        let existingByKey = decodePostgresJob(existingByKeyRow);
+        if (job.deduplicationReplace) {
+            if (existingByKeyRow.state === 'active') {
+                await clearPostgresDeduplication(tx, ctx, existingByKeyRow, now);
+            }
+            else {
+                const acquired = await tryLockPostgresDependencyCompletions(tx, ctx, [
+                    existingByKey.job.id,
+                ]);
+                if (!acquired) {
+                    await recordPostgresEvent(tx, ctx, {
+                        queue: existingByKey.job.queue,
+                        type: 'duplicated',
+                        jobId: existingByKey.job.id,
+                        occurredAt: now,
+                        job: existingByKey.job,
+                        state: existingByKey.state,
+                    });
+                    return { job: existingByKey.job, inserted: false, state: existingByKey.state };
+                }
+                await assertNoLivePostgresCompletionConsumers(tx, ctx, [existingByKey.job.id]);
+                await deleteTerminalGeneration(tx, ctx, existingByKeyRow.id);
+                await recordPostgresDeduplicationRemoval(tx, ctx, existingByKeyRow, now);
+            }
+        }
+        else {
+            if (job.deduplicationExtend && job.deduplicationTtl !== null) {
+                existingByKey = await extendPostgresDeduplication(tx, ctx, existingByKeyRow, job.deduplicationTtl, now);
+            }
+            await recordPostgresEvent(tx, ctx, {
+                queue: existingByKey.job.queue,
+                type: 'duplicated',
+                jobId: existingByKey.job.id,
+                occurredAt: now,
+                job: existingByKey.job,
+                state: existingByKey.state,
+            });
+            return { job: existingByKey.job, inserted: false, state: existingByKey.state };
+        }
+    }
+    if (existingById) {
+        await assertNoLivePostgresCompletionConsumers(tx, ctx, [job.id], options.completionConsumerExemptions);
+        await deleteTerminalGeneration(tx, ctx, String(job.id));
+    }
+    else if (!options.preparedFlow) {
+        await retirePostgresCompletionGenerations(tx, ctx, [job.id], options.completionConsumerExemptions);
+    }
+    if (!options.dependencyExistenceCheckDeferred) {
+        await assertPostgresDependenciesExist(tx, ctx, job.dependsOn);
+    }
+    if (job.runAt === job.createdAt)
+        job.runAt = now;
+    const state = postgresStateForJob(job, await postgresDependenciesSatisfied(tx, ctx, job.dependsOn), now);
+    const timelineIndex = job.timeline.length < MAX_TIMELINE_ENTRIES ? job.timeline.length : undefined;
+    if (timelineIndex !== undefined)
+        job.timeline.push({ state, timestamp: now });
+    await insertRow(tx, ctx, job, state, now);
+    if (!options.preparedFlow)
+        await registerPostgresAdmissionQueues(tx, ctx, [job.queue]);
+    const pushedEventId = options.preparedFlow
+        ? undefined
+        : await recordPostgresEvent(tx, ctx, {
+            queue: job.queue,
+            type: 'pushed',
+            jobId: job.id,
+            occurredAt: now,
+            job,
+            state,
+        });
+    if (parentQueue && job.parentId) {
+        await updatePostgresJobParentInTransaction(tx, ctx, job.id, job.parentId, true);
+    }
+    return { job, inserted: true, state, pushedEventId, timelineIndex };
+}

package/dist/infrastructure/persistence/postgres/admissionParent.d.ts

@@ -0,0 +1,5 @@
+import type { TransactionSQL } from 'bun';
+import type { Job } from '../../../domain/types/job';
+import type { PostgresContext } from './context';
+export declare function linkedPostgresParentQueue(job: Job): string | null;
+export declare function lockPostgresAdmissionParent(tx: TransactionSQL, ctx: PostgresContext, job: Job, expectedQueue: string): Promise<void>;

package/dist/infrastructure/persistence/postgres/admissionParent.js

@@ -0,0 +1,35 @@
+import { lockPostgresFlowParent } from './flowFailures';
+export function linkedPostgresParentQueue(job) {
+    if (!job.parentId ||
+        typeof job.data !== 'object' ||
+        job.data === null ||
+        Array.isArray(job.data)) {
+        return null;
+    }
+    const data = job.data;
+    if (String(data.__parentId) !== String(job.parentId))
+        return null;
+    return typeof data.__parentQueue === 'string' && data.__parentQueue.length > 0
+        ? data.__parentQueue
+        : null;
+}
+export async function lockPostgresAdmissionParent(tx, ctx, job, expectedQueue) {
+    const parentId = job.parentId;
+    if (parentId === job.id)
+        throw new Error('A job cannot be its own parent');
+    await lockPostgresFlowParent(tx, ctx, parentId);
+    const rows = await tx `
+    SELECT queue, state FROM bunqueue_jobs
+    WHERE namespace = ${ctx.config.namespace} AND id = ${String(parentId)}
+    FOR UPDATE
+  `;
+    const parent = rows[0];
+    if (!parent)
+        throw new Error(`Parent job not found: ${String(parentId)}`);
+    if (parent.queue !== expectedQueue) {
+        throw new Error(`Parent job ${String(parentId)} belongs to queue ${parent.queue}, not ${expectedQueue}`);
+    }
+    if (['active', 'completed', 'failed'].includes(parent.state)) {
+        throw new Error(`Parent job ${String(parentId)} is not linkable`);
+    }
+}

package/dist/infrastructure/persistence/postgres/admissionResult.d.ts

@@ -0,0 +1,9 @@
+import type { Job } from '../../../domain/types/job';
+import type { PostgresJobState } from './types';
+export interface PostgresAdmissionResult {
+    readonly job: Job;
+    readonly inserted: boolean;
+    readonly state: PostgresJobState;
+    readonly pushedEventId?: number;
+    readonly timelineIndex?: number;
+}

package/dist/infrastructure/persistence/postgres/admissionResult.js

@@ -0,0 +1 @@
+export {};

package/dist/infrastructure/persistence/postgres/admissionStore.d.ts

@@ -0,0 +1,12 @@
+import type { AtomicFlowBatchInput } from '../../../domain/types/flow';
+import { type Job } from '../../../domain/types/job';
+import { PostgresQueueStoreRuntime } from './runtime';
+/** Atomic single, batch, and flow admission strategy shared by the store facade. */
+export declare class PostgresAdmissionStore extends PostgresQueueStoreRuntime {
+    insert(job: Job): Promise<{
+        job: Job;
+        inserted: boolean;
+    }>;
+    insertMany(jobs: readonly Job[], rejectExisting?: boolean): Promise<Job[]>;
+    insertFlow(batch: AtomicFlowBatchInput): Promise<Job[]>;
+}

package/dist/infrastructure/persistence/postgres/admissionStore.js

@@ -0,0 +1,101 @@
+import { validateAtomicFlowBatch } from '../../../application/operations/flowValidation';
+import { createJob } from '../../../domain/types/job';
+import { admitPostgresJob } from './admission';
+import { recordPostgresJobEvents } from './batchEvents';
+import { admitPostgresJobsBatch, canBatchAdmitPostgresJobs, lockPostgresAdmissionKeys, PostgresBatchAdmissionConflict, } from './batchAdmission';
+import { retirePostgresCompletionGenerations } from './completionLifecycle';
+import { databaseNow } from './context';
+import { assertPostgresDependenciesExist, lockPostgresDependencyCompletions, } from './dependencyPromotion';
+import { lockPostgresFlowParents } from './flowFailures';
+import { PostgresQueueStoreRuntime } from './runtime';
+import { reconcilePostgresSerialAdmissions } from './serialAdmission';
+import { lockPostgresAdmissionQueues, registerPostgresAdmissionQueues } from './queueLifecycle';
+import { runPostgresTransactionWithRetry } from './transactionRetry';
+function admissionDependencyIds(jobs) {
+    return jobs.flatMap((job) => [job.id, ...job.dependsOn]);
+}
+function admissionParentIds(jobs) {
+    return jobs.flatMap((job) => (job.parentId ? [job.parentId] : []));
+}
+function replaySafeAdmissionJob(job) {
+    return { ...job, timeline: [...job.timeline] };
+}
+/** Atomic single, batch, and flow admission strategy shared by the store facade. */
+export class PostgresAdmissionStore extends PostgresQueueStoreRuntime {
+    async insert(job) {
+        await this.initialize();
+        return await runPostgresTransactionWithRetry(this.context, (tx) => admitPostgresJob(tx, this.context, replaySafeAdmissionJob(job)));
+    }
+    async insertMany(jobs, rejectExisting = false) {
+        await this.initialize();
+        const insertSerially = () => runPostgresTransactionWithRetry(this.context, async (tx) => {
+            await lockPostgresAdmissionQueues(tx, this.context, jobs.map((job) => job.queue));
+            await lockPostgresDependencyCompletions(tx, this.context, admissionDependencyIds(jobs));
+            await lockPostgresFlowParents(tx, this.context, admissionParentIds(jobs));
+            await lockPostgresAdmissionKeys(tx, this.context, jobs);
+            const admissions = [];
+            const insertedJobIds = [];
+            const insertedDependencies = [];
+            for (const source of jobs) {
+                const job = replaySafeAdmissionJob(source);
+                const admitted = await admitPostgresJob(tx, this.context, job, {
+                    rejectExisting,
+                    dependencyLocksHeld: true,
+                    queueLifecycleLocksHeld: true,
+                    dependencyExistenceCheckDeferred: true,
+                    completionConsumerExemptions: insertedJobIds,
+                });
+                admissions.push(admitted);
+                if (admitted.inserted) {
+                    insertedJobIds.push(job.id);
+                    insertedDependencies.push(...job.dependsOn);
+                }
+            }
+            await assertPostgresDependenciesExist(tx, this.context, insertedDependencies);
+            return await reconcilePostgresSerialAdmissions(tx, this.context, admissions);
+        });
+        if (!canBatchAdmitPostgresJobs(jobs))
+            return await insertSerially();
+        try {
+            return await runPostgresTransactionWithRetry(this.context, (tx) => admitPostgresJobsBatch(tx, this.context, jobs));
+        }
+        catch (error) {
+            if (!(error instanceof PostgresBatchAdmissionConflict))
+                throw error;
+            return await insertSerially();
+        }
+    }
+    async insertFlow(batch) {
+        validateAtomicFlowBatch(batch);
+        await this.initialize();
+        return await runPostgresTransactionWithRetry(this.context, async (tx) => {
+            const now = await databaseNow(tx);
+            const created = batch.jobs.map((planned) => createJob(planned.id, planned.queue, planned.input, now));
+            await lockPostgresAdmissionQueues(tx, this.context, created.map((job) => job.queue));
+            await lockPostgresDependencyCompletions(tx, this.context, admissionDependencyIds(created));
+            await retirePostgresCompletionGenerations(tx, this.context, created.map((job) => job.id));
+            await lockPostgresFlowParents(tx, this.context, admissionParentIds(created));
+            await lockPostgresAdmissionKeys(tx, this.context, created);
+            const admissionNow = await databaseNow(tx);
+            const jobs = [];
+            const admissions = [];
+            for (const job of created) {
+                const admitted = await admitPostgresJob(tx, this.context, job, {
+                    rejectExisting: true,
+                    linkParent: false,
+                    dependencyLocksHeld: true,
+                    queueLifecycleLocksHeld: true,
+                    dependencyExistenceCheckDeferred: true,
+                    preparedFlow: { now: admissionNow },
+                });
+                admissions.push(admitted);
+                jobs.push(admitted.job);
+            }
+            await assertPostgresDependenciesExist(tx, this.context, created.flatMap((job) => job.dependsOn));
+            const inserted = admissions.filter((admission) => admission.inserted);
+            await registerPostgresAdmissionQueues(tx, this.context, inserted.map(({ job }) => job.queue));
+            await recordPostgresJobEvents(tx, this.context, inserted.map(({ job, state }) => ({ job, state, type: 'pushed' })), admissionNow);
+            return jobs;
+        });
+    }
+}

package/dist/infrastructure/persistence/postgres/advisoryLocks.d.ts

@@ -0,0 +1,2 @@
+/** Build an unambiguous domain-separated advisory-lock identity. */
+export declare function postgresAdvisoryLockName(domain: string, ...components: string[]): string;

package/dist/infrastructure/persistence/postgres/advisoryLocks.js

@@ -0,0 +1,13 @@
+function postgresCharacterLength(value) {
+    // oxlint-disable-next-line typescript/no-misused-spread -- PostgreSQL length(text) counts code points.
+    return [...value].length;
+}
+/** Build an unambiguous domain-separated advisory-lock identity. */
+export function postgresAdvisoryLockName(domain, ...components) {
+    const base = `bunqueue:${domain}`;
+    if (components.length === 0)
+        return base;
+    return `${base}:${components
+        .map((component) => `${postgresCharacterLength(component)}:${component}`)
+        .join('')}`;
+}

package/dist/infrastructure/persistence/postgres/batchAdmission.d.ts

@@ -0,0 +1,11 @@
+import type { TransactionSQL } from 'bun';
+import { type Job } from '../../../domain/types/job';
+import { type PostgresContext } from './context';
+export declare class PostgresBatchAdmissionConflict extends Error {
+    constructor();
+}
+export declare function canBatchAdmitPostgresJobs(jobs: readonly Job[]): boolean;
+/** Serialize every conflicting batch key in one canonically ordered round trip. */
+export declare function lockPostgresAdmissionKeys(tx: TransactionSQL, ctx: PostgresContext, jobs: readonly Job[]): Promise<void>;
+/** Admit independent jobs atomically with one insert and one event write. */
+export declare function admitPostgresJobsBatch(tx: TransactionSQL, ctx: PostgresContext, jobs: readonly Job[]): Promise<Job[]>;

package/dist/infrastructure/persistence/postgres/batchAdmission.js

@@ -0,0 +1,128 @@
+import { MAX_TIMELINE_ENTRIES } from '../../../domain/types/job';
+import { postgresAdvisoryLockName } from './advisoryLocks';
+import { recordPostgresJobEvents } from './batchEvents';
+import { encodePostgresValue, postgresStateForJob } from './codec';
+import { databaseNow } from './context';
+import { retirePostgresCompletionGenerations } from './completionLifecycle';
+import { lockPostgresDependencyCompletions } from './dependencyPromotion';
+import { lockPostgresAdmissionQueues, registerPostgresAdmissionQueues } from './queueLifecycle';
+export class PostgresBatchAdmissionConflict extends Error {
+    constructor() {
+        super('PostgreSQL batch admission encountered an existing job ID');
+        this.name = 'PostgresBatchAdmissionConflict';
+    }
+}
+export function canBatchAdmitPostgresJobs(jobs) {
+    if (jobs.length < 2)
+        return false;
+    if (new Set(jobs.map((job) => String(job.id))).size !== jobs.length)
+        return false;
+    return jobs.every((job) => job.dependsOn.length === 0 && job.parentId === null);
+}
+function admissionKeys(jobs) {
+    return [
+        ...new Set(jobs.flatMap((job) => [
+            `id:${String(job.id)}`,
+            ...(job.uniqueKey ? [`dedup:${job.queue}:${job.uniqueKey}`] : []),
+        ])),
+    ].sort();
+}
+/** Serialize every conflicting batch key in one canonically ordered round trip. */
+export async function lockPostgresAdmissionKeys(tx, ctx, jobs) {
+    const lockNames = admissionKeys(jobs).map((key) => postgresAdvisoryLockName('admission', ctx.config.namespace, key));
+    if (lockNames.length === 0)
+        return;
+    await tx `
+    WITH ordered_keys AS MATERIALIZED (
+      SELECT DISTINCT hashtextextended(lock_name, 0) AS lock_key
+      FROM unnest(${tx.array(lockNames, 'TEXT')}) AS admission(lock_name)
+      ORDER BY lock_key
+    ), locked_keys AS MATERIALIZED (
+      SELECT lock_key, pg_advisory_xact_lock(lock_key) AS acquired
+      FROM ordered_keys
+      ORDER BY lock_key
+    )
+    SELECT COUNT(*) FROM locked_keys
+  `;
+}
+function prepareAdmissions(jobs, now) {
+    return jobs.map((job) => {
+        const preparedJob = { ...job, timeline: [...job.timeline] };
+        if (preparedJob.runAt === preparedJob.createdAt)
+            preparedJob.runAt = now;
+        const state = postgresStateForJob(preparedJob, true, now);
+        if (preparedJob.timeline.length < MAX_TIMELINE_ENTRIES) {
+            preparedJob.timeline.push({ state, timestamp: now });
+        }
+        return { job: preparedJob, state };
+    });
+}
+function toRecords(prepared, namespace, now, groupOrders) {
+    return prepared.map(({ job, state }, position) => ({
+        namespace,
+        id: String(job.id),
+        queue: job.queue,
+        payload: encodePostgresValue(job),
+        state,
+        priority: job.priority,
+        lifo: job.lifo,
+        run_at: job.runAt,
+        created_at: job.createdAt,
+        started_at: job.startedAt,
+        completed_at: job.completedAt,
+        attempts: job.attempts,
+        max_attempts: job.maxAttempts,
+        ttl: job.ttl,
+        timeout: job.timeout,
+        unique_key: job.uniqueKey,
+        unique_expires_at: job.uniqueKey && job.deduplicationTtl !== null ? now + job.deduplicationTtl : null,
+        custom_id: job.customId,
+        group_id: job.groupId,
+        group_order: groupOrders.get(position) ?? null,
+    }));
+}
+async function allocateGroupOrders(tx, prepared) {
+    const positions = prepared.flatMap(({ job }, position) => job.groupId === null ? [] : [position]);
+    if (positions.length === 0)
+        return new Map();
+    const rows = await tx `
+    WITH ordered AS MATERIALIZED (
+      SELECT position
+      FROM unnest(${tx.array(positions, 'INTEGER')}) AS requested(position)
+      ORDER BY position
+    )
+    SELECT position, nextval('bunqueue_group_order_seq') AS group_order
+    FROM ordered
+    ORDER BY position
+  `;
+    return new Map(rows.map(({ position, group_order }) => [position, group_order]));
+}
+async function insertRows(tx, ctx, prepared, now) {
+    const groupOrders = await allocateGroupOrders(tx, prepared);
+    const records = toRecords(prepared, ctx.config.namespace, now, groupOrders);
+    let insertedCount = 0;
+    for (let offset = 0; offset < records.length; offset += 1000) {
+        const batch = records.slice(offset, offset + 1000);
+        const inserted = await tx `
+      INSERT INTO bunqueue_jobs ${tx(batch, 'namespace', 'id', 'queue', 'payload', 'state', 'priority', 'lifo', 'run_at', 'created_at', 'started_at', 'completed_at', 'attempts', 'max_attempts', 'ttl', 'timeout', 'unique_key', 'unique_expires_at', 'custom_id', 'group_id', 'group_order')}
+      ON CONFLICT DO NOTHING
+      RETURNING id
+    `;
+        insertedCount += inserted.length;
+    }
+    if (insertedCount !== prepared.length)
+        throw new PostgresBatchAdmissionConflict();
+}
+/** Admit independent jobs atomically with one insert and one event write. */
+export async function admitPostgresJobsBatch(tx, ctx, jobs) {
+    await lockPostgresAdmissionQueues(tx, ctx, jobs.map((job) => job.queue));
+    await lockPostgresDependencyCompletions(tx, ctx, jobs.map((job) => job.id));
+    await lockPostgresAdmissionKeys(tx, ctx, jobs);
+    const now = await databaseNow(tx);
+    const prepared = prepareAdmissions(jobs, now);
+    await insertRows(tx, ctx, prepared, now);
+    await registerPostgresAdmissionQueues(tx, ctx, prepared.map(({ job }) => job.queue));
+    await retirePostgresCompletionGenerations(tx, ctx, jobs.map((job) => job.id));
+    await recordPostgresJobEvents(tx, ctx, prepared.map(({ job, state }) => ({ job, type: 'pushed', state })), now);
+    return prepared.map(({ job }) => job);
+}

package/dist/infrastructure/persistence/postgres/batchCompletion.d.ts

@@ -0,0 +1,4 @@
+import { type PostgresContext } from './context';
+import type { PostgresBatchCompletionResult, PostgresCompletionInput } from './types';
+/** Complete a unique ACK batch atomically with set-based persistence. */
+export declare function completePostgresJobs(ctx: PostgresContext, inputs: readonly PostgresCompletionInput[]): Promise<PostgresBatchCompletionResult[]>;