Queue
Queues: durable background work, delivered at least once.
jobs = noclick.Queue.from_name("invoices", create_if_missing=True)
jobs.put({"invoice": "INV-1042"})
for msg in jobs.iterate(lease_s=60):
print("Sending", msg.body["invoice"])
msg.ack()A message you take is leased to you for lease_s seconds: ack() it when
the work is done, or it comes back for another try (so handle a message twice
safely). A message that fails max_attempts times moves to the dead letters,
where you can retry or discard it. An agent can take the messages instead:
triggers=[noclick.OnQueue(jobs)] makes each one a turn.
class QueueA durable queue of JSON messages, delivered at least once. put adds work; get and
iterate take it under a lease. Queue.fromName("invoices", { createIfMissing: true }) is
lazy. There's no Queue.get(id), since get takes a message: Queue.fromId(id).hydrate().
- Like every live object, it also has hydrate(), refresh() and raw.
| id | string | |
| name | string | |
| depth | number | Messages waiting to be taken, delayed ones included (as of the last load; |
| inFlight | number | Messages leased and not yet acked. |
| deadLetterCount | number | Messages that failed |
| maxAttempts | number | Deliveries a message gets before it's a dead letter. |
| usedBy | UsedBy[] | Who consumes it: agents with an |
| region | RegionName | null | The region it keeps its data in, fixed when it was created. |
| userId | string | null | |
| createdAt | Date | null | |
| consoleUrl | string | null | This queue in the developer console (null off the hosted API). |
createstatic
static create(name: string, options?: QueueCreateOptions): Promise<Queue>Create a queue, unique by name per user (a taken name throws Conflict with existingId). region
keeps its messages there for good: us-east only for now (another, or a default elsewhere, throws
InvalidRequest).
Deliveries a message gets before it's a dead letter (1 to 100; 5 by default).
Where it runs or keeps its data (regions()); omitted, your account's default region.
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
The new queue, empty.
fromNamestatic
static fromName(
name: string,
options?: QueueCreateOptions & { createIfMissing?: boolean },
): QueueA lazy reference to the queue called name. With createIfMissing it's created on first
use; a maxAttempts you pass is also applied to one that already exists.
Deliveries a message gets before it's a dead letter (1 to 100; 5 by default).
null)Where it runs or keeps its data (regions()); omitted, your account's default region.
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
A queue that loads (or is created) on first use. Nothing is sent yet.
fromIdstatic
static fromId(queueId: string, options?: CallOptions): QueueA lazy reference by id; await Queue.fromId(id).hydrate() loads it now.
A queue that loads the first time you use it. Nothing is sent yet.
liststatic
static list(options?: ReadOptions & { limit?: number }): Promise<Queue[]>The current user's queues (or those userFilter covers), newest first.
Return at most this many.
Which users the read covers (user_id query), instead of acting as one (user).
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
Every matching queue, newest first, fetched page by page.
listPagestatic
static listPage(options?: ReadOptions & PageOptions): Promise<Page<Queue>>One page of queues; pass nextCursor back as cursor.
The next_cursor of the page before; omit it for the first page.
Return at most this many.
Which users the read covers (user_id query), instead of acting as one (user).
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
A page whose data holds the queues and whose next_cursor is None on the last page.
update
update(options: { maxAttempts: number }): Promise<this>Change how many deliveries a message gets before it's a dead letter (1 to 100).
This queue, with its new max_attempts.
put
put(
body: unknown,
options?: { delayS?: number; dedupeKey?: string },
): Promise<string>Add a message (any JSON, up to 256 KB), hidden for delayS seconds (up to 7 days). Its id.
dedupeKey (up to 128 characters) makes the put safe to repeat: for 24 hours another put with
the same key adds nothing and returns the first message's id.
The new message's id (the first one's, for a repeated dedupe_key).
putMany
putMany(
bodies: readonly unknown[],
options?: { delayS?: number },
): Promise<string[]>Add up to 100 messages in one call, all or none. Their ids, in order.
The new messages' ids, in the order you gave them.
get
get(
options?: { timeoutS?: number; leaseS?: number },
): Promise<QueueMessage | null>Take the next message, waiting up to timeoutS seconds (at most 60; 0 by default) for one.
It's leased for leaseS seconds (60 by default, up to 12 hours). Null if none arrived.
060The message, or None if none arrived in time.
iterate
async *iterate(
options?: { leaseS?: number; signal?: AbortSignal; stopWhenEmpty?: boolean },
): AsyncGenerator<QueueMessage>Take messages as they arrive, each leased for leaseS; long-polls until you break or signal
aborts. With stopWhenEmpty it ends instead the first time nothing is waiting (messages leased
to someone else, or delayed, don't keep it going), to drain a queue in a batch job.
60Each message as it's taken. Without stop_when_empty it never ends on its own, so break when you're done.
size
size(): Promise<number>How many messages wait (delayed included; leased and dead letters not), read now.
The queue's depth.
peek
peek(options?: { limit?: number }): Promise<QueueMessage[]>The oldest messages, waiting and in flight, without taking them (nothing is leased).
Return at most this many.
10)Up to limit (at most 100) messages, with their status and attempts.
deadLetters
deadLetters(options?: { limit?: number }): Promise<QueueMessage[]>The messages that failed maxAttempts times, newest first; kept 14 days.
Return at most this many.
Every dead letter (or the first limit), fetched page by page.
depthHistory
depthHistory(options?: { hours?: number }): Promise<QueueDepth[]>How deep the queue has been over the last hours (24 by default, up to 168), a point every 15 minutes.
24A QueueDepth (at, depth, in_flight) per point, oldest first.
clear
clear(): Promise<void>Drop every waiting message and every dead letter; messages in flight finish as usual.
export
export(): Promise<Operation<ExportBundle>>Export every message as it stands at one moment, dead letters included, as JSON Lines: one per
line, oldest first, with its status (waiting, delayed, in_flight or dead), attempts
and body. wait() resolves to an ExportBundle: a zip at url holding the file.
An operation whose wait() gives an ExportBundle: a zip at url holding the files.
delete
delete(): Promise<TrashItem>Delete the queue and its messages: it goes to the trash, restorable for 30 days. One an app binds
or an OnQueue trigger reads throws Conflict. Returns its TrashItem.
Its TrashItem: restore() puts it back, messages and all.
QueueMessage
class QueueMessageOne message on a queue. A message you took with get or iterate is leased to you until
leaseExpiresAt: ack() when done, nack() to hand it back now as a failed try, release() to
hand it back without spending one. A dead letter (from
deadLetters()) says why its last attempt failed in lastError; retry() puts it back and
discard() deletes it.
- Like every live object, it also has hydrate(), refresh() and raw.
| id | string | |
| queueId | string | |
| body | unknown | The message as you put it: JSON. |
| status | QueueMessageStatus |
|
| attempts | number | How many times it has been delivered, this delivery included. |
| enqueuedAt | Date | null | |
| visibleAt | Date | null | When a delayed message can first be taken (null once it can). |
| leaseExpiresAt | Date | null | When your lease ends and the message goes back (null unless you hold it). |
| lastError | string | null | Why its last attempt failed (null if none has). |
| deadLetteredAt | Date | null | When it became a dead letter (null unless it is one). |
ack
ack(): Promise<void>Mark it done: deleted, never delivered again. A late ack (the lease ran out) throws Conflict.
nack
nack(options?: { delayS?: number; error?: string }): Promise<void>Hand it back for another try after delayS seconds; it counts as an attempt. error (up to
2 KB) says why: it's the message's lastError, which a dead letter keeps.
release
release(options?: { delayS?: number }): Promise<void>Hand it back untouched after delayS seconds without spending an attempt (attempts goes back,
lastError stays): for a failure that isn't the message's, like an account out of money, so a
backlog doesn't burn its tries. It keeps coming back until the cause is fixed.
retry
retry(): Promise<void>Put a dead letter back on the queue, with its attempts reset.
discard
discard(): Promise<void>Delete a dead letter for good.
QueueDepth
interface QueueDepthHow full a queue was at one moment.
| at | Date | null | |
| depth | number | |
| inFlight | number |