HyperdriveJobQueue

Defined in: packages/messaging/src/adapters/cloudflare/hyperdrive-job-queue.ts:125

A job queue in a SQL table on D1 or another SQLite, Postgres (Hyperdrive) or MySQL.

With leaseMs, a processing job’s process_at holds its lease’s end, so the table needs no new column. dequeue() settles expired leases and takes the next job with statements that each settle or take a job only once: Postgres skips rows another dequeue() has locked, SQLite runs each statement under its write lock, and MySQL locks the rows it changes, which holds only when the client provides transaction(). Without onLeaseExpired, Postgres does both in one statement; with it, the callbacks run between the two, so they do not shorten the new lease.

A job already processing without a lease, taken by an earlier version or by a queue without leaseMs, cannot be told from one whose lease has expired, so it is due at once.

Type Parameters

T

T

Implements

JobQueue<T>

Constructors

Constructor

new HyperdriveJobQueue<T>(client, options?): HyperdriveJobQueue<T>

Defined in: packages/messaging/src/adapters/cloudflare/hyperdrive-job-queue.ts:133

Parameters

client

CloudflareSqlClient

options?

HyperdriveJobQueueOptions<T> = {}

Returns

HyperdriveJobQueue<T>

Methods

checkpoint()

checkpoint(jobId, data, attempt): Promise<void>

Defined in: packages/messaging/src/adapters/cloudflare/hyperdrive-job-queue.ts:256

Saves a message job’s progress under the attempt fence and, with leaseMs, renews the lease. Needs a cache-disabled Hyperdrive: when the driver reports no affected-row count, ownership is verified with a plain read, which a query cache could answer with a stale row.

Parameters

jobId

string

data

T

attempt

number

Returns

Promise<void>

Implementation of

JobQueue.checkpoint

cleanupTerminal()

cleanupTerminal(options?): Promise<number>

Defined in: packages/messaging/src/adapters/cloudflare/hyperdrive-job-queue.ts:477

Removes finished jobs: completed and failed ones by default, or those with the given statuses, and with olderThan, only those that finished before it.

Parameters

options?

JobQueueCleanupOptions | JobStatus[]

Returns

Promise<number>

Implementation of

JobQueue.cleanupTerminal

clear()

clear(): Promise<void>

Defined in: packages/messaging/src/adapters/cloudflare/hyperdrive-job-queue.ts:467

Returns

Promise<void>

Implementation of

JobQueue.clear

close()

close(): Promise<void>

Defined in: packages/messaging/src/adapters/cloudflare/hyperdrive-job-queue.ts:518

Returns

Promise<void>

complete()

complete(jobId, _result?, options?): Promise<void>

Defined in: packages/messaging/src/adapters/cloudflare/hyperdrive-job-queue.ts:283

Parameters

jobId

string

_result?

any

options?

JobSettleOptions = {}

Returns

Promise<void>

Implementation of

JobQueue.complete

dequeue()

dequeue(options?): Promise<Job<T> | undefined>

Defined in: packages/messaging/src/adapters/cloudflare/hyperdrive-job-queue.ts:230

Takes the next due job and, with leaseMs, leases it. Jobs whose lease expired are due again first, or fail when they have no attempts left. Jobs in options.running are left as they are.

Parameters

options?

JobDequeueOptions = {}

Returns

Promise<Job<T> | undefined>

Implementation of

JobQueue.dequeue

enqueue()

enqueue(type, data, options?): Promise<Job<T>>

Defined in: packages/messaging/src/adapters/cloudflare/hyperdrive-job-queue.ts:164

Parameters

type

string

data

T

options?

{ delay?: number; maxAttempts?: number; metadata?: Record<string, any>; priority?: number; } | undefined

Returns

Promise<Job<T>>

Implementation of

JobQueue.enqueue

fail()

fail(jobId, error, retry?, options?): Promise<void>

Defined in: packages/messaging/src/adapters/cloudflare/hyperdrive-job-queue.ts:317

Counts a failed attempt: the job is due again after retry.delayMs when retries are enabled and attempts are left, and fails otherwise. A completed job stays completed, even for a worker whose lease expired, unless options.attempt fences the call to the attempt that owns it.

Parameters

jobId

string

error

string | Error

retry?

JobRetryDirective = ...

options?

JobSettleOptions = {}

Returns

Promise<void>

Implementation of

JobQueue.fail

getJob()

getJob(jobId): Promise<Job<T> | undefined>

Defined in: packages/messaging/src/adapters/cloudflare/hyperdrive-job-queue.ts:437

Parameters

jobId

string

Returns

Promise<Job<T> | undefined>

Implementation of

JobQueue.getJob

init()

init(): Promise<void>

Defined in: packages/messaging/src/adapters/cloudflare/hyperdrive-job-queue.ts:146

Returns

Promise<void>

nextDueAt()

nextDueAt(): Promise<Date | undefined>

Defined in: packages/messaging/src/adapters/cloudflare/hyperdrive-job-queue.ts:423

When dequeue() next has work: the earliest due time of a pending job or, with leaseMs, lease expiry of a processing one. A time in the past means dequeue() has work now, even when it only settles an expired lease, so call dequeue() rather than checking size(). undefined when no job is pending or leased.