Queue

In-memory job queue with priorities, delayed execution, retry, dead-letter, pause/resume

Package: @robinpath/queue | Category: Infrastructure | Type: Utility

Authentication

No authentication required. All functions are available immediately.

Use Cases

Use the queue module when you need to:

• Create a named job queue -- Use queue.create to perform this operation
• Add a job to a queue with optional priority and delay -- Use queue.push to perform this operation
• Get the next pending job from a queue (highest priority, oldest first) -- Use queue.pop to perform this operation
• Mark a job as completed with an optional result -- Use queue.complete to perform this operation
• Mark a job as failed; auto-retries if under maxAttempts, otherwise moves to dead-letter -- Use queue.fail to perform this operation

Quick Reference

Function	Description	Returns
create	Create a named job queue	Queue configuration
push	Add a job to a queue with optional priority and delay	{id, status, priority}
pop	Get the next pending job from a queue (highest priority, oldest first)	Job object or null if queue is empty/paused
complete	Mark a job as completed with an optional result	{id, status, duration}
fail	Mark a job as failed; auto-retries if under maxAttempts, otherwise moves to dead-letter	{id, status: 'retry' or 'dead-letter', attempts}
retry	Re-queue a failed or dead-letter job for processing	{id, status, source}
remove	Remove a job from a queue	True if job was removed
size	Get the number of jobs in a queue, optionally filtered by status	Number of jobs
status	Get detailed status and metrics for a queue	Queue status with counts by job status
pause	Pause a queue (pop will return null)	{name, paused: true}
resume	Resume a paused queue	{name, paused: false}
clear	Remove all jobs from a queue	{cleared: number}
deadLetter	List jobs in the dead-letter queue	Array of failed jobs
getJob	Get details for a specific job by ID	Job details or null
destroy	Destroy a queue and free all resources	True if queue existed

Functions

create

Create a named job queue

Module: queue | Returns: object -- Queue configuration

queue.create "emails"

Parameter	Type	Required	Description
name	string	Yes	Queue name
options	object	No	{maxDeadLetter: number}

---

push

Add a job to a queue with optional priority and delay

Module: queue | Returns: object -- {id, status, priority}

queue.push "emails" $emailData {"priority": 10}

Parameter	Type	Required	Description
queue	string	Yes	Queue name
data	any	Yes	Job data/payload
options	object	No	{priority, delay, maxAttempts}

---

pop

Get the next pending job from a queue (highest priority, oldest first)

Module: queue | Returns: object -- Job object or null if queue is empty/paused

queue.pop "emails"

Parameter	Type	Required	Description
queue	string	Yes	Queue name

---

complete

Mark a job as completed with an optional result

Module: queue | Returns: object -- {id, status, duration}

queue.complete "emails" $jobId "sent"

Parameter	Type	Required	Description
queue	string	Yes	Queue name
jobId	string	Yes	Job ID
result	any	No	Optional result data

---

fail

Mark a job as failed; auto-retries if under maxAttempts, otherwise moves to dead-letter

Module: queue | Returns: object -- {id, status: 'retry' or 'dead-letter', attempts}

queue.fail "emails" $jobId "SMTP timeout"

Parameter	Type	Required	Description
queue	string	Yes	Queue name
jobId	string	Yes	Job ID
error	string	Yes	Error message

---

retry

Re-queue a failed or dead-letter job for processing

Module: queue | Returns: object -- {id, status, source}

queue.retry "emails" $jobId

Parameter	Type	Required	Description
queue	string	Yes	Queue name
jobId	string	Yes	Job ID

---

remove

Remove a job from a queue

Module: queue | Returns: boolean -- True if job was removed

queue.remove "emails" $jobId

Parameter	Type	Required	Description
queue	string	Yes	Queue name
jobId	string	Yes	Job ID

---

size

Get the number of jobs in a queue, optionally filtered by status

Module: queue | Returns: number -- Number of jobs

queue.size "emails" "pending"

Parameter	Type	Required	Description
queue	string	Yes	Queue name
status	string	No	Filter: pending, active, completed, failed, delayed

---

status

Get detailed status and metrics for a queue

Module: queue | Returns: object -- Queue status with counts by job status

queue.status "emails"

Parameter	Type	Required	Description
queue	string	Yes	Queue name

---

pause

Pause a queue (pop will return null)

Module: queue | Returns: object -- {name, paused: true}

queue.pause "emails"

Parameter	Type	Required	Description
queue	string	Yes	Queue name

---

resume

Resume a paused queue

Module: queue | Returns: object -- {name, paused: false}

queue.resume "emails"

Parameter	Type	Required	Description
queue	string	Yes	Queue name

---

clear

Remove all jobs from a queue

Module: queue | Returns: object -- {cleared: number}

queue.clear "emails"

Parameter	Type	Required	Description
queue	string	Yes	Queue name

---

deadLetter

List jobs in the dead-letter queue

Module: queue | Returns: array -- Array of failed jobs

queue.deadLetter "emails" 10

Parameter	Type	Required	Description
queue	string	Yes	Queue name
limit	number	No	Max entries (default 50)

---

getJob

Get details for a specific job by ID

Module: queue | Returns: object -- Job details or null

queue.getJob "emails" $jobId

Parameter	Type	Required	Description
queue	string	Yes	Queue name
jobId	string	Yes	Job ID

---

destroy

Destroy a queue and free all resources

Module: queue | Returns: boolean -- True if queue existed

queue.destroy "emails"

Parameter	Type	Required	Description
queue	string	Yes	Queue name

---

Error Handling

All functions throw on failure. Common errors:

Error	Cause
Job "..." not found in queue "..."	Check the error message for details
Job "..." not found	Check the error message for details

@desc "Create and validate result"
do
  set $result as queue.create "emails"
  if $result != null
    print "Success"
  else
    print "No result"
  end
enddo

Recipes

1. List and iterate Job

Retrieve all items and loop through them.

@desc "Get job and iterate results"
do
  set $result as queue.getJob "emails" $jobId
  each $item in $result
    print $item
  end
enddo

2. Create a new item with create

Create a new resource and capture the result.

set $result as queue.create "emails"
print "Created: " + $result

3. Check before creating

List existing items and only create if needed.

@desc "Get job and create"
do
  set $existing as queue.getJob "emails" $jobId
  if $existing == null
    queue.create "emails"
    print "Item created"
  else
    print "Item already exists"
  end
enddo

4. Multi-step Queue workflow

Chain multiple queue operations together.

@desc "Create, push, and more"
do
  set $r_create as queue.create "emails"
  set $r_push as queue.push "emails" $emailData {"priority": 10}
  set $r_pop as queue.pop "emails"
  print "All operations complete"
enddo

5. Safe create with validation

Check results before proceeding.

@desc "Create and validate result"
do
  set $result as queue.create "emails"
  if $result != null
    print "Success: " + $result
  else
    print "Operation returned no data"
  end
enddo

Related Modules

• json -- JSON module for complementary functionality