Queues

Queue helpers store named FIFO lists in Kicklet's runtime queue storage. They are useful for simple song-like queues, shoutout queues, or short-lived viewer lists.

Limits: default accounts can have 1 runtime queue with up to 30 items, and one item can be up to 500 bytes. Premium accounts can have 20 runtime queues with up to 100000 items each, and one item can be up to 2 KB. Runtime queues are removed automatically after 24 hours without use.

Engine v2

Push queue item with status

Adds a value to a named persistent runtime queue and returns a status object instead of throwing for expected limit errors.

Join queue with limit handlingAdvanced Script

const result = queue.tryPush("shoutouts", sender.username);

if (result.limitReached) {
  async.messages.send("The queue is full right now.");
} else {
  async.messages.send(`You are position ${result.position}.`);
}

Join queue once with costAdvanced Script

const result = queue.tryPush("shoutouts", sender.username, { unique: true });

if (result.limitReached) {
  async.messages.send("The queue is full right now.");
} else if (result.pushed) {
  points.remove(sender.username, 10);
  async.messages.send(`You joined at position ${result.position}.`);
} else {
  async.messages.send(`You are already in the queue at position ${result.position}.`);
}

Join queue with custom limitAdvanced Script

const maxEntries = 10;

if (queue.size("shoutouts") >= maxEntries) {
  async.messages.send("The shoutout queue already has 10 entries.");
} else {
  const result = queue.tryPush("shoutouts", sender.username, { unique: true });

  if (result.limitReached) {
      async.messages.send("The queue is full right now.");
  } else if (result.pushed) {
      points.remove(sender.username, 10);
      async.messages.send(`You joined at position ${result.position}.`);
  } else {
      async.messages.send(`You are already in the queue at position ${result.position}.`);
  }
}

API reference

queue.tryPush

queue.tryPush(name, value, options?)

Input

name

string

Queue name.

value

any

Value to add.

optionsoptional

object

Optional push settings.

uniqueoptional

boolean

When true, the same stored JSON value is only queued once.

Output

object

Queue push status.

ok

boolean

False when a limit prevented the operation.

position

number

Queue position after the push, existing position when unique prevented a duplicate, or 0 when not queued.

count

number

Queue length after the operation, or 0 when not queued.

pushed

boolean

True when a new item was added. False when unique found an existing item or a limit prevented the push.

limitReached

boolean

True when a queue count, item count, or item size limit was reached.

error

string

Backend error message for limit failures.

Push queue item

Adds a value to a named persistent runtime queue. Returns 0 when a queue limit prevents the push. Use queue.tryPush() when you need status details.

Join queueAdvanced Script

const position = queue.push("shoutouts", sender.username);
async.messages.send(`You are position ${position}.`);

API reference

queue.push

queue.push(name, value, options?)

Input

name

string

Queue name.

value

any

Value to add.

optionsoptional

object

Optional push settings.

uniqueoptional

boolean

When true, the same stored JSON value is only queued once.

Output

number

Queue position after the push, or the existing position when unique prevented a duplicate.

Pop queue item

Removes and returns the oldest item from a named queue.

Next queue itemAdvanced Script

const next = queue.pop("shoutouts");
async.messages.send(next ? `Next: ${next}` : "Queue is empty.");

API reference

queue.pop

queue.pop(name)

Input

name

string

Queue name.

Output

anynull

Oldest item, or null when empty.

Peek queue item

Returns the oldest item from a named queue without removing it.

Preview next queue itemAdvanced Script

const next = queue.peek("shoutouts");
async.messages.send(next ? `Next up: ${next}` : "Queue is empty.");

API reference

queue.peek

queue.peek(name, options?)

Input

name

string

Queue name.

optionsoptional

object

Optional list settings passed to queue.list().

pageSizeoptional

number

Maximum number of items to inspect.

Output

anynull

Oldest item, or null when empty.

List queue items

Returns a copy of the first items in the current named queue without removing them.

Show the next queue itemsAdvanced Script

const items = queue.list("shoutouts", { pageSize: 5 });

if (items.length === 0) {
  async.messages.send("The shoutout queue is empty.");
} else {
  async.messages.send(`Next shoutouts: ${items.join(", ")}`);
}

API reference

queue.list

queue.list(name, options?)

Input

name

string

Queue name.

optionsoptional

object

Optional list settings.

pageSizeoptional

number

Maximum number of items to return. Defaults to 100 and is clamped from 1 to 500.

Output

any[]

Queued values in FIFO order. Item IDs and timestamps are not included.

Get queue size

Returns the current number of items in a named runtime queue.

Check queue sizeAdvanced Script

const count = queue.size("shoutouts");
async.messages.send(`The shoutout queue has ${count} entries.`);

API reference

queue.size

queue.size(name)

Input

name

string

Queue name.

Output

number

Current queue length.

Remove queue item

Removes queued values that exactly match the provided value.

Remove one queue itemAdvanced Script

const removed = queue.remove("shoutouts", sender.username);

if (removed === 0) {
  async.messages.send("You were not in the shoutout queue.");
} else {
  async.messages.send("You were removed from the shoutout queue.");
}

Remove all matching queue itemsAdvanced Script

const removed = queue.remove("shoutouts", sender.username, { all: true });
async.messages.send(`Removed ${removed} matching queue entries.`);

API reference

queue.remove

queue.remove(name, value, options?)

Input

name

string

Queue name.

value

any

Value to remove. Objects and arrays must match the stored JSON value.

optionsoptional

object

Optional remove settings.

alloptional

boolean

When true, removes every matching value. Defaults to false, which removes only the first match.

Output

number

Number of removed items.

Clear queue

Deletes a named runtime queue and all of its queued items.

Clear all queue itemsAdvanced Script

queue.clear("shoutouts");
async.messages.send("The shoutout queue was cleared.");

API reference

queue.clear

queue.clear(name)

Input

name

string

Queue name.

Output

boolean

True when the clear operation completed.

Async queue wrappers

Async wrapper for queue.tryPush(name, value, options?).

API reference

async.queue.tryPush

async.queue.tryPush(name, value, options?)

Input

name

string

Queue name.

value

any

Value to add.

optionsoptional

object

Optional push settings.

uniqueoptional

boolean

When true, the same stored JSON value is only queued once.

Output

object

Queue push status.

ok

boolean

False when a limit prevented the operation.

position

number

Queue position after the push, existing position when unique prevented a duplicate, or 0 when not queued.

count

number

Queue length after the operation, or 0 when not queued.

pushed

boolean

True when a new item was added. False when unique found an existing item or a limit prevented the push.

limitReached

boolean

True when a queue count, item count, or item size limit was reached.

error

string

Backend error message for limit failures.

Async wrapper for queue.push(name, value, options?).

API reference

async.queue.push

async.queue.push(name, value, options?)

Input

name

string

Queue name.

value

any

Value to add.

optionsoptional

object

Optional push settings.

uniqueoptional

boolean

When true, the same stored JSON value is only queued once.

Output

number

Queue position after the push, or the existing position when unique prevented a duplicate.

Async wrapper for queue.pop(name).

API reference

async.queue.pop

async.queue.pop(name)

Input

name

string

Queue name.

Output

anynull

Oldest item, or null when empty.

Async wrapper for queue.peek(name, options?).

API reference

async.queue.peek

async.queue.peek(name, options?)

Input

name

string

Queue name.

optionsoptional

object

Optional list settings passed to queue.list().

pageSizeoptional

number

Maximum number of items to inspect.

Output

anynull

Oldest item, or null when empty.

Async wrapper for queue.list(name, options?).

API reference

async.queue.list

async.queue.list(name, options?)

Input

name

string

Queue name.

optionsoptional

object

Optional list settings.

pageSizeoptional

number

Maximum number of items to return. Defaults to 100 and is clamped from 1 to 500.

Output

any[]

Queued values in FIFO order. Item IDs and timestamps are not included.

Async wrapper for queue.size(name).

API reference

async.queue.size

async.queue.size(name)

Input

name

string

Queue name.

Output

number

Current queue length.

Async wrapper for queue.remove(name, value, options?).

API reference

async.queue.remove

async.queue.remove(name, value, options?)

Input

name

string

Queue name.

value

any

Value to remove. Objects and arrays must match the stored JSON value.

optionsoptional

object

Optional remove settings.

alloptional

boolean

When true, removes every matching value. Defaults to false, which removes only the first match.

Output

number

Number of removed items.

Async wrapper for queue.clear(name).

API reference

async.queue.clear

async.queue.clear(name)

Input

name

string

Queue name.

Output

boolean

True when the clear operation completed.

Engine v1

Use variables to store an array-like value manually.